HTMLDetailsBox

The HTMLDetailsBox function creates and displays a details box. A details box contains a message and title, a Details button to show or hide additional information, plus any combination of command buttons as well as an optional icon.

Unlike the Platform SDK MessageBox function, the HTMLDetailsBox function can use a list of custom buttons, automatically remove itself after a given period of time, display a check box to allow the user to prevent the details box from displaying in the future, and automatically handle the Help button. HTMLDetailsBox supports displaying rich message and details text using simple HTML tagging described below.

int HTMLDetailsBox(
  HWND hParent,                    // handle to the parent window (can omit if using MFC)
  LPCTSTR messageText,             // pointer to text in details box
  LPCTSTR titleText,               // pointer to title of details box
  LPCTSTR detailsText,             // pointer to details text
  SIZE detailsSize,                // size of the details edit box, in dialog units
  BOOL & showUnfolded,             // if TRUE, the details information is displayed
  UINT type = MB_OK,               // style of details box
  LPCTSTR displayInFutureText = 0, // pointer to display in future text
  HTMLButtonList *pButtonList = 0, // pointer to a custom button list
  int timeoutSeconds = -1,         // automatic timeout time
  int iconResource = -1,           // icon resource ID
  UINT helpID = 0                  // help context ID
);

int HTMLDetailsBox(
  HWND hParent,                    // handle to the parent window (can omit if using MFC)
  UINT messageID,                  // the text string resource ID
  UINT titleID,                    // the title string resource ID
  LPCTSTR detailsText,             // pointer to details text
  SIZE detailsSize,                // size of the details edit box, in dialog units
  BOOL & showUnfolded,             // if TRUE, the details information is displayed
  UINT type = MB_OK,               // style of details box
  LPCTSTR displayInFutureText = 0, // pointer to display in future text
  HTMLButtonList *pButtonList = 0, // pointer to a custom button list
  int timeoutSeconds = -1,         // automatic timeout time
  int iconResource = -1,           // icon resource ID
  UINT helpID = 0                  // help context ID
);

HWND HTMLDetailsBoxModeless(
  HWND hParent,                    // handle to the parent window (can omit if using MFC)
  LPCTSTR messageText,             // pointer to text in details box
  LPCTSTR titleText,               // pointer to title of details box
  LPCTSTR detailsText,             // pointer to details text
  SIZE detailsSize,                // size of the details edit box, in dialog units
  BOOL & showUnfolded,             // if TRUE, the details information is displayed
  UINT type = MB_OK,               // style of details box
  LPCTSTR displayInFutureText = 0, // pointer to display in future text
  HTMLButtonList *pButtonList = 0, // pointer to a custom button list
  int timeoutSeconds = -1,         // automatic timeout time
  int iconResource = -1,           // icon resource ID
  UINT helpID = 0                  // help context ID
);

HWND HTMLDetailsBoxModeless(
  HWND hParent,                    // handle to the parent window (can omit if using MFC)
  UINT messageID,                  // the text string resource ID
  UINT titleID,                    // the title string resource ID
  LPCTSTR detailsText,             // pointer to details text
  SIZE detailsSize,                // size of the details edit box, in dialog units
  BOOL & showUnfolded,             // if TRUE, the details information is displayed
  UINT type = MB_OK,               // style of details box
  LPCTSTR displayInFutureText = 0, // pointer to display in future text
  HTMLButtonList *pButtonList = 0, // pointer to a custom button list
  int timeoutSeconds = -1,         // automatic timeout time
  int iconResource = -1,           // icon resource ID
  UINT helpID = 0                  // help context ID
);

Parameters

hParent

Handle to the parent window. This parameter can be omitted if using MFC.

messageText

Pointer to a null-terminated string containing the message to be displayed in the details box. Note that you can use simple HTML tagging, as described below.

messageID

A resource ID for the string containing the message to be displayed in the details box. Note that you can use simple HTML tagging, as described below.

titleText

Pointer to a null-terminated string containing the details box title. If NULL or empty, the program name is used.

titleID

A resource ID for the string containing the details box title. If NULL or empty, the program name is used.

detailsText

Pointer to a null-terminated string containing the details text to be displayed. The details text does not support HMTL tagging.

detailsSize

The width and height of the details edit box, in dialog units.

showUnfolded

A reference to a BOOL that determines if the details information should be displayed initially. The return value indicates the state of the details information when the details box was closed.

displayInFutureText

Pointer to a null-terminated string containing the text for the Don't Display in Future check box. This check box is not displayed if the text is NULL or empty.

pButtonList

Pointer to a custom button list, as described below, or NULL if not used.

timeoutSeconds

The number of seconds to wait before the details box times out, returning HTMLID_TIMEOUT. If this value is 0 or less, no timeout occurs.

iconResource

A resource ID for a custom details box icon, or a value of 0 or less for no icon.

helpID

The help context ID for the details box help, or a value of 0 if none.

type

A combination of flags ORed together to specify the contents and behavior of the dialog box. This parameter can be a set of flags from the following groups:

Buttons Flag
Use one of the following flags to specify the buttons contained in the details box. These flags are ignored if pButtonList contains a button list:

Flag Meaning

HTMLMB_CANCEL Specifies one push button: Cancel.

HTMLMB_CONTINUE Specifies one push button: Continue.

MB_OK Specifies one push button: OK. This is the default.

MB_OKCANCEL Specifies two push buttons: OK and Cancel.

MB_RETRYCANCEL Specifies two push buttons: Retry and Cancel.

MB_YESNO Specifies two push buttons: Yes and No.

MB_YESNOCANCEL Specifies three push buttons: Yes, No, and Cancel.

Flag	Meaning
HTMLMB_CANCEL	Specifies one push button: Cancel.
HTMLMB_CONTINUE	Specifies one push button: Continue.
MB_OK	Specifies one push button: OK. This is the default.
MB_OKCANCEL	Specifies two push buttons: OK and Cancel.
MB_RETRYCANCEL	Specifies two push buttons: Retry and Cancel.
MB_YESNO	Specifies two push buttons: Yes and No.
MB_YESNOCANCEL	Specifies three push buttons: Yes, No, and Cancel.

Icon Flag
Use one of the following flags to display an icon in the details box. The icon flag is ignored if an icon resource ID is provided by the iconResource parameter.

Flag Meaning

MB_ICONEXCLAMATION,
MB_ICONWARNING An exclamation-point icon appears in the details box.

MB_ICONINFORMATION, MB_ICONASTERISK An icon consisting of a lowercase letter i in a circle appears in the details box.

MB_ICONQUESTION A question-mark icon appears in the details box.

MB_ICONSTOP,
MB_ICONERROR,
MB_ICONHAND A stop-sign icon appears in the details box.

Flag	Meaning
MB_ICONEXCLAMATION, MB_ICONWARNING	An exclamation-point icon appears in the details box.
MB_ICONINFORMATION, MB_ICONASTERISK	An icon consisting of a lowercase letter i in a circle appears in the details box.
MB_ICONQUESTION	A question-mark icon appears in the details box.
MB_ICONSTOP, MB_ICONERROR, MB_ICONHAND	A stop-sign icon appears in the details box.

Default Button Flag
Specify one of the following flags to indicate the default button. If the default button flag is not specified, the first button will be the default button. The default button flag is ignored if a button list is provided.

Flag Meaning

MB_DEFBUTTON1 Make the first button the default button.

MB_DEFBUTTON2 Make the second button the default button.

MB_DEFBUTTON3 Make the third button the default button.

MB_DEFBUTTON4 Make the Help button the default button, regardless of the number of buttons.

Flag	Meaning
MB_DEFBUTTON1	Make the first button the default button.
MB_DEFBUTTON2	Make the second button the default button.
MB_DEFBUTTON3	Make the third button the default button.
MB_DEFBUTTON4	Make the Help button the default button, regardless of the number of buttons.

Return Values

The return value is zero if there is not enough memory to create the details box.

For the HTMLDetailsBox functions, if the function succeeds, the return value is the ID of the selected button, such as IDOK, IDCANCEL, IDABORT, IDRETRY, IDIGNORE, IDYES, and IDNO. The value IDOK is also returned by the Continue button. For the HTMLDetailsBoxModeless functions, the return value is a handle to the modeless dialog box (HWND), which must be destroyed by the calling program using DestroyWindow.

If a timeout occurs before the user responds to the details box, the return value is HTMLID_TIMEOUT.

If a string provided for displayInFutureText and the user unchecks the box, HTMLID_DONTASKAGAIN is ORed in to the return value.

Description

The details text supports HTML tagging. If not using HTML tagging for the details text, use a carriage return and line feed (that is, "\r\n") for line breaks.

The Details button is automatically provided as the last button, so you don't need to specify it. You can specify the Details button in a custom button list by assigning a button an ID of HTMLID_DETAILS_BUTTON, only the button location is honored since the given button name is ignored.

To provide context sensitive help, provide a non-zero value for the helpID parameter and call the HTMLSetHelp function to set the help file. The MB_HELP flag is ignored.

If you use an automatic timeout by providing a value greater than zero for the timeoutSeconds parameter, make the timeout long enough that the user has a chance to respond to the message. Automatic timeouts are best used to prevent a details box from preventing a task from continuing. Large timeout values such as 300 seconds (5 minutes) are effective.

The result of providing the displayInFutureText parameter is to display the text and have HTMLID_DONTASKAGAIN ORed in to the return value. The calling function is responsible for suppressing the details box in the future.

You can set the font used by the message box functions using the HTMLSetFont function. You can set the message box button justification (center or right) using the HTMLSetCenterButtons function.

HTML Tagging

The message text may contain simple HTML tagging. HTML text is identified by starting with the <HTML> tag and ending with the </HTML> tag. Only the <HTML>, <H1>, <H2>, <H3>, <H4>, <P>, <B>, <I>, <CODE>, <BIG>, <SMALL>, and <BR> tags are supported. Newlines are not supported in HTML text, so you must use the <BR> tag to break lines. The < and > characters are supported to display the less than and greater than characters.

For the best results, use the HTML tagging with restraint.

Custom Button Lists

You can specify the details box buttons using either a custom button list or the button flags, such as MB_OK. The button flags are ignored if a button list is supplied. To create a button list, create an HTMLButtonList array and for each button specify the name, ID number, and whether the button is the default button. The buttons are displayed in the order of the items in the button list array. The list must be terminated by an entry with an ID of -1.

Modeless Operation

When using the HTMLDetailsBoxModeless functions, you can change the message text by calling GetDlgItem(HTMLID_MESSAGE_TEXT) and then SetWindowText. Similarly, you can change the details text by calling GetDlgItem(HTMLID_DETAILS_TEXT) and then SetWindowText. You can obtain the modeless return value by calling HTMLModelessReturnValue. You also need to provide a message loop so that the details box can continue to receive messages and you should check to see if the user has finished with the details box by calling HTMLModelessReturnValue within the message loop. A typical modeless details box handler is as follows:


   HWND     hParent, hDetails;
   MSG      msg;
   int      retVal;

   // display the details box
   hDetails = HTMLDetailsBoxModeless(hParent, _T("<HTML>A <B>modeless</B> details box.</HTML>"));

   // do processing
   while (DoSomeProcessing())
   {
      // check to see if the user has canceled
      if ((retVal = HTMLModelessReturnValue(hDetails)) >= 0)
         break;
      while (PeekMessage(&msg, 0, 0, 0, PM_REMOVE))
      {
         TranslateMessage(&msg);
         DispatchMessage(&msg);
      }
   }

   // get returned value (and do whatever you want with it)
   retVal = HTMLModelessReturnValue(hDetails);

   // destroy the modeless dialog
   DestroyWindow(hDetails);   // DestroyWindow deletes dialog

Note that if the user dismisses a modeless details box, the window is hidden but not destroyed so the window handle is valid until you call DestroyWindow.

Sample Code

A typical details box:


   #include "CtlHtml.h"

   BOOL showUnfolded = FALSE;
   SIZE size;

   size.cx = 200;
   size.cy = 40'
   HTMLDetailsBox(hParent, _T("This is a test."), _T("Custom Title"), 
         _T("<HTML>This is the very long details text with<BR>a bunch of mumbo jumbo to test the details</HTML>"),
         size, showUnfolded, MB_RETRYCANCEL | MB_ICONSTOP);

A typical details box

A typical details box with a Don't Display in Future check box (using MFC):


   BOOL showUnfolded = FALSE;

   HTMLDetailsBox(_T("This is a test."), _T("Custom Title"), 
         _T("This is the very long details text with\r\na bunch of mumbo jumbo to test the details"),
         CSize(200, 40), showUnfolded, MB_RETRYCANCEL | MB_ICONSTOP | MB_DEFBUTTON2, 
         _T("Don't display this message in the future."));

A typical details box with a Don't Display in Future check box

An HTML text details box with the program name for the title (using MFC):


   BOOL showUnfolded = TRUE;     // to initially show the details

   HTMLDetailsBox(_T("<HTML>This is an example of<BR><B>HTML text</B>.</HTML>"), 
         _T("Custom Title"),
         _T("This is the very long details text with\r\na bunch of mumbo jumbo to test the details"),
         CSize(200, 40), showUnfolded, HTMLMB_CONTINUE | MB_ICONSTOP);

An HTML text details box with the program name for the title

A button list details box:


   HTMLButtonList buttonList[4];
   BOOL showUnfolded = FALSE;
   SIZE size;

   size.cx = 200;
   size.cy = 40'

   buttonList[0].Name = "&Apple";
   buttonList[0].ID   = 100;
   buttonList[0].IsDefault = TRUE;

   buttonList[1].Name = "&Banana";
   buttonList[1].ID   = 101;
   buttonList[1].IsDefault = FALSE;

   buttonList[2].Name = "&Carrot";
   buttonList[2].ID   = 102;
   buttonList[2].IsDefault = FALSE;

   buttonList[3].ID   = -1;

   HTMLDetailsBox(hParent, _T("This is a test."), _T("Button List Test"), 
         _T("This is the very long details text with\r\na bunch of mumbo jumbo to test the details"),
         size, showUnfolded, MB_RETRYCANCEL | MB_ICONSTOP, 0, buttonList);

A button list details box